home *** CD-ROM | disk | FTP | other *** search
-
- The Mesa 3-D graphics library
-
- Version 1.2.1
-
- Copyright (C) 1995 Brian Paul
-
-
-
- Introduction
- ============
-
- Mesa is a 3-D graphics library with an API which is very similar to that
- of OpenGL*. To the extent that Mesa utilizes the OpenGL command syntax
- or state machine, it is being used with authorization from Silicon Graphics,
- Inc. However, the author makes no claim that Mesa is in any way a
- compatible replacement for OpenGL or associated with Silicon Graphics, Inc.
- Those who want a licensed implementation of OpenGL should contact a licensed
- vendor. This software is distributed under the terms of the GNU Library
- General Public License, see the LICENSE file for details.
-
- * OpenGL(R) is a registered trademark of Silicon Graphics, Inc.
-
-
-
- Author
- ======
-
- Brian Paul
- Space Science and Engineering Center
- University of Wisconsin - Madison
- 1225 W. Dayton St.
- Madison, WI 53706
-
- brianp@ssec.wisc.edu
-
-
-
- Status
- ======
-
- I've been working on this library in my spare time since August, 1993.
- It's currently about 90% complete. You'll find that most programs which
- use the OpenGL tk, aux or GLUT toolkits will work with Mesa without changing
- the source code at all.
-
- Features which are complete:
- all glBegin() primitives
- all model and view transformations
- clipping (against user clip planes and view volume)
- lighting
- smooth shading
- depth buffering
- accumulation buffer
- alpha testing/blending
- stencil buffer
- dithering
- logic operations
- evaluators (curves and surfaces)
- feedback/selection
- fog (per-pixel or per-vertex)
- polygon/line stippling
- read/write/copy pixels
- tk and aux libraries for X11
- context switching (multiple windows)
- RGB mode simulated in color mapped windows
- the GLX library (as close as I can get)
-
- Features which are mostly complete:
- display lists
- texture mapping
- the GLU library
-
- Missing features:
- anti-aliasing
- mipmapping, non-point-sampled texture mapping
- NURBS
- glPixelZoom
-
- The primary goal of this library has been correctness, speed was secondary
- (but not neglected!). Many optimizations can still be done.
-
- The core library was originally written on an Amiga using the DCC compiler.
- Later on it was moved to an SGI. Current development is done on an SGI
- system.
-
- Mesa works on most Unix workstations with ANSI C and X11. Now there's also
- a Microsoft Windows driver (see windows/README.WIN). A very outdated and
- inoperative Amiga driver is also included.
-
- While a 24-bit TrueColor display is recommended for RGB mode rendering,
- the Mesa/X driver supports rendering on 8-bit and even 1-bit displays by
- dithering.
-
- Please send bug reports to the author. Include information describing
- your system, which version of Mesa you're using, and how to reproduce the
- problem. Bug fixes are especially welcome. Note that some parts of Mesa
- (widgets, GLU tesselator, GLE library, etc) were contributed by others and
- any bugs in those components should be sent to the respective author.
-
-
-
- Manifest
- ========
-
- The archive file Mesa-1.2.1.tar.Z can be unpacked with:
- zcat Mesa-1.2.1.tar.Z | tar xvf -
-
- After you unpacking you should have the following:
-
- Mesa/README - this file
- Mesa/LICENSE - the GNU library license
- Mesa/Makefile - top-level Makefile
- Mesa/Make-config - system configurations used by the Makefiles
- Mesa/include/ - application include files
- Mesa/lib/ - application libraries, directory created by make
- Mesa/src/ - source code for core library
- Mesa/src-glu/ - source code for utility library
- Mesa/src-tk/ - source code for tk library
- Mesa/src-aux/ - source code for aux library
- Mesa/demos/ - demo programs
- Mesa/samples/ - sample OpenGL programs from SGI
- Mesa/book/ - example programs from the OpenGL Programming Guide
- Mesa/GLUT/ - the home for GLUT
- Mesa/widgets/ - the Mesa widgets
- Mesa/contrib/ - user contributed software
- Mesa/windows/ - Microsoft Windows driver stuff
-
-
- Installation for Unix/X11
- =========================
-
- To compile the library, first type 'make' alone to see the list of system
- configurations currently supported. If you see your configuration on the
- list, type 'make <system>'. Most popular Unix/X workstations are currently
- supported.
-
- The top-level makefile will execute the makefiles in a number of sub-
- directories. When finished, there should be executables in the "demos/",
- "samples/", and "book/" directories for you to try out.
-
- If your system is not listed by 'make', you'll have to modify the top-level
- Makefile and Make-config files. There are instructions in each file.
-
- If you have compilation problems you should try to fix them and return the
- patches to the author.
-
- The file src/config.h has many parameters which you can tune before building.
-
- If you want to build the Mesa widgets read the widgets/INSTALL file.
-
- If you want to build the GLUT library read the GLUT/README-MESA file.
-
-
-
- Installation for Microsoft Windows
- ==================================
-
- See the windows/README.WIN file for details. Note that any problems with
- the Windows driver should be addressed to Mark Peterson. Also, be aware
- that this is a preliminary release of the Windows driver; there are prob-
- ably bugs.
-
-
-
- Using the library (with Unix/X11 systems)
- =========================================
-
- To use the library with your own applications you may want to move the
- files in "include/" to "/usr/local/include/" and the libraries in "lib/"
- to "/usr/local/lib/". Then compile your graphics application with
- "-I/usr/local/include" and link with "-L/usr/local/lib -lMesaGL -lMesaGLU",
- for example. Look at the demos/Makefile for an example.
-
- Since the OpenGL API is used, OpenGL documentation can serve as the
- documentation for Mesa's core functions.
-
- Initially, you may write your own Mesa programs using the aux or tk tool-
- kits which are used in the OpenGL Programming Guide and in SGI's demos,
- respectively. However, these toolkits weren't meant for use in real app-
- lications. You have several alternatives:
-
- 1. Go directly to the X/Mesa interface using the functions described in
- include/GL/xmesa.h. This requires experience with X programming.
-
- 2. Use the GLX (simulated since Mesa doesn't implement the GLX extension)
- functions. These functions look like, and try to act like, the real GLX
- functions used by OpenGL in conjunction with the X window system.
-
- 3. GLUT (OpenGL Utility Toolkit) was written by Mark Kilgard at SGI as
- a replacement for aux and tk. It provides a simple, portable, window-
- system independent interface allowing you to write OpenGL applications
- quickly and easily. GLUT isn't included with Mesa but you'll find instruc-
- tions on how to get and build GLUT in the file GLUT/README-MESA.
-
- 4. Use a Mesa widgets. Look in the widgets/ directory for more info.
-
-
- A few tips on getting the best performance from Mesa:
-
- 1. Turn off smooth shading when you don't need it (glShadeModel)
- 2. Turn off depth buffering when you don't need it.
- 3. Use double buffering as it's often faster than single buffering
- 4. Compile in the X Shared Memory extension option if it's supported
- on your system by adding -DSHM to CFLAGS and -lXext to XLIBS for
- your system in the Make-config file.
- 5. Recompile Mesa with more optimization if possible.
- 6. Try to maximize the amount of drawing done between glBegin/glEnd pairs.
- 7. Use the MESA_BACK_BUFFER variable to find best performance in double
- buffered mode.
-
-
- Debugging: normally Mesa records but does not notify the user of errors.
- It is up to the application to call glGetError to check for errors. Mesa
- supports an environment variable, MESA_DEBUG, to help with debugging. If
- MESA_DEBUG is defined, a message will be printed to stdout when an error
- occurs.
-
-
- Display Modes: The glXChooseVisual function tries its best to pick an
- appropriate visual for the given attribute list. However, if this doesn't
- suit your needs you can force Mesa to use any X visual you want (though not
- all are supported) by setting the MESA_RGB_VISUAL and MESA_CI_VISUAL envi-
- ronment variables. When an RGB visual is requested, glXChooseVisual will
- first look if the MESA_RGB_VISUAL variable is defined. If so, it will try
- to use the specified visual. Similarly, when a color index visual is re-
- quested, glXChooseVisual will look for the MESA_CI_VISUAL variable.
-
- The format of accepted values is: <visual-class> <depth>
- Here are some examples:
-
- using the C-shell:
- % setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor
- % setenv MESA_CI_VISUAL "PseudoColor 12" // 12-bit PseudoColor
- % setenv MESA_RGB_VISUAL "PseudoColor 8" // 8-bit PseudoColor
-
- using the KornShell:
- $ export MESA_RGB_VISUAL="TrueColor 8"
- $ export MESA_CI_VISUAL="PseudoColor 12"
- $ export MESA_RGB_VISUAL="PseudoColor 8"
-
-
- Another environment variable, MESA_BACK_BUFFER, controls whether the back
- buffer (for double buffering) is implemented using an X Pixmap or XImage.
- A pixmap is faster when drawing simple lines and polygons while an XImage
- is faster when Mesa has to do pixel-by-pixel rendering. Using the
- MESA_BACK_BUFFER variable you can experiment to see which is faster for
- your application. The valid values for MESA_BACK_BUFFER are: Pixmap and
- XImage (only the first letter is checked, case doesn't matter).
-
-
- While Mesa includes its own header files GL/gl.h GL/glx.h GL/glu.h you can
- optionally compile Mesa using the real OpenGL header files if you have
- them. Just remove or move the GL/gl.h GL/glx.h GL/glu.h Mesa files and
- replace them with copies or links to the real OpenGL header files. Then
- recompile Mesa.
-
-
-
- Miscellaneous
- =============
-
- See the src/NOTES file for more detailed info about the implementation
- of Mesa. See the book/NOTES and samples/NOTES files for information
- about which demos work or don't work, and why.
-
- The latest version of Mesa can be found at iris.ssec.wisc.edu in pub/misc/
-
- There is a Mesa WWW page: http://www.ssec.wisc.edu/~brianp/Mesa.html
-
- There is a Mesa mailing list. To subscribe, send the following message to
- the address listserv@iqm.unicamp.br
-
- subs mesa <your name>
- set mesa mail ack
-
- For example:
-
- subs mesa Brian Paul
- set mesa mail ack
-
- The second line tells the list processor to send you a copy of your own
- messages.
-
- You will receive a welcome message from the list server when you have been
- added to the list. It tells you how to post messages to the list, how
- to unsubscribe, etc. Thanks to Pedro Vazquez for setting up the list.
-
- There is a contrib/ subdirectory containing contributions from Mesa users.
- See the README file in that directory for more information.
-
-
-
- Known Bugs
- ==========
-
- Polygons with two nearly-co-located vertices may be mis-rendered or acciden-
- tally culled.
-
- Perspective-corrected texture map coordinate interpolation can fail under
- certain conditions due to numerical error.
-
-
-
- Version History
- ===============
-
- 1.0 beta February 1995
- Initial release
-
- 1.1 beta March 4, 1995
- Many improvements:
- - faster point and line drawing (2x faster)
- - more systems supported, better Makefiles
- - many small bug fixes
- - pseudo-GLX functions added
- - GLUT support
- - new implementation of evaluators (eval2.c)
- - Renamed lib*.a files to avoid collisions
-
- 1.1.1 beta March 7, 1995
- Reverted from eval2.c to eval.c due to FPE on Linux
- more speed improvements
- more Makefile changes
-
- 1.1.2 beta March 14,1995
- Using eval2.c again
- more FPE-prevention checks (0-length normals are OK)
- a few small bug fixes
- much faster pixel logic ops!
- faster transformation arithmetic
- implementation of SGI's blending extensions
- glXUseXFont implemented
- added MESA_DEBUG environment variable support
-
- 1.1.3 beta March 31,1995
- gluScaleImage() and gluBuild2DMipMaps() implemented
- Mesa widgets for Xt/Motif
- more bug fixes
- blendEXT demos
- added environment variables for selecting visuals
- almost all GLUT demos work correctly now
- faster X device driver functions
-
- 1.1.4 beta April 20,1995
- Bug fixes:
- - missing #define SEEK_SET in src-tk/image.c
- - compile glShadeModel into display lists
- - fixed pow() domain error in src/light.c
- - fixed "flickering bitmaps" in double buffer mode
- - fixed tk.h and aux.h for C++
- - state of LIGHT_MODEL_LOCAL_VIEWER was inverted
- New features:
- - MUCH, MUCH nicer dithering in 8-bit RGB mode
- - updated widgets and widget demos
- - Implemented GLXPixmap functions
- - Added GLU 1.1 and GLX 1.1 functions
- - Changed the X/Mesa interface API, more versatile
- - Implemented gluPartialDisk()
-
- 1.2 May 22,1995
- Bug fixes:
- - IRIX 4.x makefile problem
- - modified tk to share root colormap as needed
- - gluLookAt normalization problem
- - suppress Expose, NoExpose events in swapbuffers
- - glBitmap() and glDrawPixels() clipping
- New features:
- - GL_BLEND, GL_MODULATE, GL_DECAL, and GL_REPLACE_EXT texture
- modes implemented
- - texture maps stored more efficiently
- - texture maps can be compiled into display lists
- - Bogdan Sikorski's GLU polygon tesselation code
- - Linas Vepstas's sweep and extrusion library
- - glXCreateContext()'s shareList parameter works as it's supposed to.
- XMesaCreateContext() updated to accept a shareList parameter too.
- - Mesa can be compiled with real OpenGL .h files
- - MESA_BACK_BUFFER environment variable
- - better GLX error checking
-
- 1.2.1 June 22, 1995
- Bug fixes:
- - X/Mesa double buffer window resize crash
- - widgets now pass PointerMotion events
- - X/Mesa incorrect default clear color and drawing color
- - more robust X MIT-SHM support in X/Mesa
- - glTexImage( format=GL_LUMINANCE ) didn't work
- - GL_LINE mode polygons with line width > 1.0 could cause a crash
- - numerous feedback bugs
- - glReadPixels() from depth buffer was wrong
- - error prone depth and stencil buffer allocation
- New features:
- - Preliminary Microsoft Windows driver
- - Implemented a number of missing functions: glEvalCoord[12][df]v(),
- glGet...(), etc.
- - Added a few missing symbols to gl.h and glu.h
- - Faster rendering of smooth-shaded, RGBA, depth-buffered polygons.
- - Faster rendering of lines when width=2.0
- - Stencil-related functions now work in display lists
- Changes:
- - renamed aux.h as glaux.h (MS-DOS names can't start with aux)
- - most filenames are in 8.3 format to accomodate MS-DOS
- - use GLubytes to store arrays of colors instead of GLints
-
- Coming up...
- All new triangle rasterization
-
-
-
- Why is it the library called Mesa?
- ==================================
-
- Why not? More obvious names were considered but had to be rejected:
- FreeGL (too similar to the trademarked name OpenGL), Free3D (too similar
- to DEC's Open3D). Also, I'm tired of acronyms.
-
- [I've recently discovered that at least two other software products use the
- name Mesa. A name change may be necessary in the future. Suggestions are
- welcome!]
-
-
-
- Thanks to
- =========
-
- Erich Stefan Boleyn - for the glRotate code and testing early Mesa
- Joe Kiniry, Kendall Bennett - for opinions and discussion
- Marc Buffat - for the gluProject and gluUnproject functions
- Bernd Barsuhn, Volker Weiss - for the new implementation of evaluators
- Philip Brown - for the initial GLX, GLUT implementation
- Thorsten Ohl - for glXUseXFont() and glBitmap bug fixes
- Thomas Malik - for new invert_matrix and other xform.c code
- Michael Pichler - for X colormap code
- Thorsten Ohl, Jeroen van der Zijp - for the widget set
- Bob Mercier - for the new 8-bit RGB dithering code
- Pedro Vazquez - for establishing the Mesa mailing list
- Bogdan Sikorski - for the GLU polygon tesselation code
- Linas Vepstas - for his extrusion and swept surface library
- Frederic Devernay - for improved X shared memory support
- Asif Khan - for bringing _many_ subtle bugs to my attention
- Mark Peterson - for the MS Windows driver for Mesa
-
-
- Your contributionss are greatly appreciated!
-
-
-
- This file last revised: 22 June 1995
-